Panel VAR Modeling
===================

(Panel reduced-form VAR -- the modern factory is
``prfvar_model``, which extends the reduced-form VAR object to a
cross-section of units.)

A ``prfvar_model`` object models a **panel** of (possibly
Markov-switching) reduced-form VARs: the same set of variables
observed for several cross-sectional units (countries, sectors,
...), stacked into one system whose coefficients are linked
across units according to a chosen *homogeneity* assumption. It
extends the reduced-form VAR object, so data handling,
estimation, identification, forecasting and the various
decompositions are exactly as in :doc:`Main Reduced form VAR Modeling`; this
page covers what is specific to the panel case.

.. contents::
   :local:
   :depth: 2


The model
----------

Stacking the :math:`n` units gives

.. math::

   \left[
   \begin{array}{c}
   y_{1t} \\
   y_{2t} \\
   \vdots  \\
   y_{nt}
   \end{array}
   \right] =
   C(r_{t})
   \left[
   \begin{array}{c}
   x_{1t} \\
   x_{2t} \\
   \vdots  \\
   x_{nt}
   \end{array}
   \right] +
   B_{1}(r_{t})
   \left[
   \begin{array}{c}
   y_{1t-1} \\
   y_{2t-1} \\
   \vdots  \\
   y_{nt-1}
   \end{array}
   \right] + \cdots +
   B_{p}(r_{t})
   \left[
   \begin{array}{c}
   y_{1t-p} \\
   y_{2t-p} \\
   \vdots  \\
   y_{nt-p}
   \end{array}
   \right] + u_{t}

with :math:`r_{t} = 1, 2, \dots, h` and transition probabilities
:math:`p_{r_{t}, r_{t+1}}(I_{t})`. The blocks
:math:`B_{1}, \dots, B_{p}` (dynamic / lag coefficients, named
``b1``, ..., ``bp`` -- ``b(row, col)``, with the lag index
omitted, refers to all lags) and :math:`C` (deterministic /
exogenous coefficients, named ``c``) carry, on and off the
diagonal, both within-unit and cross-unit dynamics. How much of
this is shared across units is governed by the homogeneity
assumption:

* ``'pooled'`` -- all units share the same coefficients;
* ``'meanGroup'`` -- mean-group estimator (average across units);
* ``'static'`` -- the deterministic (constant / exogenous)
  coefficients are common, the dynamics are unit-specific;
* ``'dynamic'`` -- the lag coefficients are common, the constants
  are unit-specific;
* ``'independent'`` -- nothing in common (a separate VAR per
  unit).


Creating a panel VAR
---------------------

The first argument is a ``panel`` struct describing the
cross-section; the rest of the signature is the
``rfvar_model`` one::

    panel             = struct();
    panel.members     = {'US','CA','MX','BR'};
    panel.homogeneity = 'dynamic';

    endog = {'GROWTH','PAI','R'};

    mdl = prfvar_model(panel, endog, ...
        lag_length    = 4, ...
        constant_term = true);

You declare the variables once (``endog``) and the units once
(``panel.members``); internally RISE expands the variable list
by appending the unit names -- ``GROWTH_US``, ``GROWTH_CA``,
..., ``PAI_US``, ... -- so the time-series database you pass to
``estimate`` should carry those per-unit series. RISE's panel
data handling takes care of the stacking;
``translate_panel_output`` gives the results back unit by unit.
The list of units and the homogeneity of an existing object are
available through ``members`` and ``homogeneity``.


Estimation, identification, IRFs, decompositions, forecasting
---------------------------------------------------------------

These are called exactly as for a reduced-form VAR --
``estimate`` (with an optional prior built from
``var_priors.minnesota(...)`` and any linear restrictions on the
``b`` / ``c`` coefficients), ``identification`` (and then
``structural_shocks`` / ``irf`` with the resulting ``Rfunc``),
``variance_decomposition``, ``historical_decomposition``,
``forecast``, ``bootstrap``. Restrictions are written on the
*expanded* parameter names (``b1(GROWTH_US, R_CA) = 0`` for a
cross-unit exclusion, etc.), but the homogeneity assumption
already imposes the bulk of the cross-unit structure. See
:doc:`Main Reduced form VAR Modeling` for the call patterns and the plotting
helpers (``quick_irfs``, ``plot_fanchart``, ``plot_decomp``).


Adding regime switching
------------------------

Pass a Markov-chain structure through the ``markov_chains``
keyword and list the parameters it controls (on the expanded
names). Time-varying transition probabilities are specified
exactly as in :doc:`Main Reduced form VAR Modeling`, and the switching
parameters are given priors through ``estim_priors``.